home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 451-475 / disk_451 / convert / convert.doc < prev    next >
Text File  |  1992-05-06  |  10KB  |  239 lines
  1. ===========================================================
  2.  Convert.doc - for v1r6 - last updated November 15th, 1990
  3. ===========================================================
  4.  
  5. Credits:
  6. --------
  7. Software created by Pete Patterson for Black Belt Systems
  8. Additional coding by Ben Williams
  9. Documentation written by Ben Williams
  10. Funding by Black Belt Systems
  11. Project: HAM-E hardware support
  12.  
  13. Program revisions from version 1.0 to date:
  14. ===========================================
  15. v1r6 - Fixed bug causing crashes if memory allocation failed
  16.      - Intergerized scaling for approximately 7x speed improvement
  17.  
  18. v1r5 - Fixed bug in loading 24 bit files that appeared in v1r4
  19.      - Added load of IBM (yech!) Dpaint "LBM" files
  20.      - Added load of IBM DPaint non-LBM files (recent DPaint versions)
  21.      - Added "shuffle" features to convert from and to X-Spex
  22.        compatible 3-d interleaved images
  23.  
  24. v1r4 - Added support for 18 bit IFF "ScanLab" files
  25.      - Added Support for Black Belt paint UPB8 (UnPackedBrush-8) brushes
  26.  
  27. v1r3 - Added HAM-E ham and reg mode single and multi field loaders
  28.  
  29. v1r2 - Added ability to read one type of targa file ("Opticks" generated)
  30.  
  31. v1r1 - Fixed bug in loading RGB8 and RGN files in v1r0
  32.      - Added scaling options (-px, -py, -%x, -%y)
  33.  
  34. v1r0 - Initial release version.
  35.  
  36. Introduction:
  37. -------------
  38. The convert tool was created to fill a specific need of the Black Belt
  39. Systems HAM-E product customer base. The HAM-E is a graphics device
  40. which can display color information far more accurately than the Amigas
  41. built in graphics capabilities allow. As such, the HAM-E display
  42. formatting software takes as input CBM standard 24 bit IFF files, the
  43. format defined by CBM specifically for this type of use.
  44.  
  45. Unfortunately, many otherwise powerful Amiga products such as Impulses
  46. Turbo Silver, Byte by Bytes Sculpt series and some of the PD ray trace
  47. products don't save standard files; instead, they save raw files,
  48. or partially (sometimes totally!) non-conformant "other" formats, some
  49. of which they consider proprietary.
  50.  
  51. Certain other software products often save image formats that are
  52. designed to take advantage of various features in the Amiga's graphics
  53. system that allow enhancement of certain image modes. HAM-E, SHAM and
  54. Dynamic HiRes are examples of this type of image file. ASDGs "The Art
  55. Department" saves 24 bit files with special chunks in them called
  56. "CLUT" chunks that modify the 24 bit data in various ways. All of these
  57. differing image file formats bring chaos to our supposedly orderly
  58. "standard image format" environment.
  59.  
  60. The convert tool is able to read many of these file formats, optionally
  61. scale the input file to a new size for output, and write it out as a
  62. completely standard, "100% vanilla" 24 bit IFF file as per the CBM
  63. specification. Once this is done, the resulting file can be sent to the
  64. HAM-E render software, or any other Amiga tool that can read 24 bit IFF.
  65.  
  66. The convert tool has been made available free of charge to our
  67. customers as a service to them. Use by other parties is allowable as
  68. well.
  69.  
  70. Use of Convert:
  71. ---------------
  72. There are basically two types of image files that convert supports.
  73. First, we have "unified" image files. These are files where all of the
  74. iamge information is contained in one file, with enough other
  75. information to allow the convert tool to identify the file type and
  76. then act accordingly. The other is "raw" individual RGB files, where
  77. three individual files make up the complete image; and there is no
  78. information in these files to help the tool know what the file type is,
  79. or what its resolution is, and so on.
  80.  
  81. Unified Image File Use:
  82. -----------------------
  83. This consists of simply specifying an input and an output file:
  84.  
  85.     1> convert -i input_file -o output_file
  86.  
  87. This will take the input file and create a 24 bit IFF output file of
  88. the same resolution. The filenames may be presented in any order, as
  89. long as they are preceeded by the "-i" and "-o" switches. Note that for
  90. Targa format files, you must specify the -t flag anywhere on the command
  91. line. The width and height of the image is stored within the Targa file,
  92. but there is nothing in a Targa format file which identifies it as such.
  93.  
  94. Raw Image File Use:
  95. -------------------
  96. For any raw RGB file triplet, the "-i" option is not used. Instead,
  97. there are five (5) required command line switches that tell the convert
  98. software how to deal with this image. You must provide the names of
  99. each of the three raw files, as well as the horizontal and vertical
  100. resolution of the image contained in these files. Here is an example:
  101.  
  102.     1> convert -r file1 -g file2 -b file3 -x 320 -y 400 -o output_file
  103.  
  104. The parameters may be presented in any order, as long as all five of
  105. the -o, -r, -g, -b, -x, and -y switches are present.
  106.  
  107. Optional Output Scaling:
  108. ------------------------
  109. For either unified file types or raw RGB files, you have the option to
  110. scale the output file. You can do this as a percentage of input size,
  111. or to specific X:Y output requirements, or a mixture of both
  112. techniques. For the examples we'll use the unified form of the command
  113. since it's shorter and a little easier to understand; but these scaling
  114. options may also be applied in exactly the same way to raw RGB file
  115. conversion operations. Here are some examples:
  116.  
  117.     1> convert -i infile -o outfile -%x 50
  118.  
  119. This will scale the X axis to 50% of the original size. Since there is
  120. no scale specification for the Y axis, it will remain the original
  121. size.
  122.  
  123. If you need to scale both axis to 50%, then you specify that for both:
  124.  
  125.     1> convert -i infile -o outfile -%x 50 -%y 50
  126.  
  127. You can specify the output size directly in pixels, as well. The
  128. following example will create a 320x400 output, regardless of the size
  129. of the input file:
  130.  
  131.     1> convert -i infile -o outfile -px 320 -py 400
  132.  
  133. And this will scale the x axis to 50% of it's original size while
  134. ensuring a 200 line vertical size:
  135.  
  136.     1> convert -i infile -o outfile -%x 50 -py 200
  137.  
  138. You can mix and match percent and specific X and Y options as needed;
  139. don't use a percentage and a specific pixel specification for the same
  140. axis.
  141.  
  142. The scaling options also allow enlargement. For percentages, just
  143. specify values greater than 100; for pixel sizes, if the output size is
  144. larger than the input file size, then the output file will be enlarged
  145. in that dimension or dimensions. Here's an example:
  146.  
  147.     1> convert -i infile -o outfile -%x 200 -%y 200
  148.  
  149. Unified Image File Formats Supported:
  150. -------------------------------------
  151.  1 - 2 color IFF images
  152.  2 - 4 color IFF images
  153.  3 - 8 color IFF images
  154.  4 - 16 color IFF images
  155.  5 - 32 color IFF images
  156.  6 - 64 color "half-bright" IFF images
  157.  7 - 64 color HAM-E register mode single field images
  158.  8 - 64 color HAM-E register mode dual field images
  159.  9 - 128 color HAM-E register mode single field images
  160. 10 - 128 color HAM-E register mode dual field images
  161. 11 - 128 color IFF images
  162. 12 - 192 color HAM-E register mode single field images
  163. 13 - 192 color HAM-E register mode dual field images
  164. 14 - 256 color IFF images
  165. 15 - 256 color GIF images
  166. 16 - 256 color HAM-E register mode single field images
  167. 17 - 256 color HAM-E register mode dual field images
  168. 18 - 256 color HAM-E UPB8 brushes
  169. 19 - 4096 color photon paint IFF images
  170. 20 - 4096 color photon paint IFF brushes
  171. 21 - 4096 color DigiPaint IFF images
  172. 22 - 4096 color DigiPaint IFF brushes
  173. 23 - 4096 color Dynamic HiRes images
  174. 24 - 4096 color ARZ0 images ("TAD")
  175. 25 - 4096 color ARZ1 images ("TAD")
  176. 26 - 4096 color AHAM images ("TAD")
  177. 27 - 4096 color SHAM images ("info")
  178. 28 - 4096 color RGBN images ("Silver")
  179. 29 - 262144 color HAM-E ham mode single field images
  180. 30 - 262144 color HAM-E ham mode single field, multi-bank images
  181. 31 - 262144 color HAM-E ham mode dual field images
  182. 32 - 262144 color HAM-E ham mode dual field, multi-bank images
  183. 33 - 262144 color "ScanLab" 18 bit IFF files
  184. 34 - 16 million color RGB8 ("Silver")
  185. 35 - 16 million color 24-bit IFF images with CLUT chunks ("TAD")
  186. 36 - 16 million color 24-bit IFF images
  187. 37 - 16 million color QRT Trace files
  188. 38 - 16 million color DKB Trace files
  189. 39 - 16 million color TARGA files (Opticks)
  190.  
  191. Available Command Line Switches:
  192. ================================
  193.  
  194. For Help
  195. --------
  196. ?                 ...for list of options
  197. h                 ...for list of options
  198. -h                ...for list of options
  199. help              ...for list of options
  200.  
  201. For Specifying a Unified Input File:
  202. ------------------------------------
  203. -i [dev:dir/file]     ...unified input file (may include path)
  204.  
  205. For Specifying Targa Input:
  206. ---------------------------
  207. -t                    ...use -i for Targa file name
  208.  
  209. For Specifying raw RGB Input Files (All these switches are required):
  210. ---------------------------------------------------------------------
  211. -r [dev:dir/file]     ...raw red file (may include path)
  212. -g [dev:dir/file]     ...raw green file (may include path)
  213. -b [dev:dir/file]     ...raw blue file (may include path)
  214. -x [width]            ...raw source width
  215. -y [height]           ...raw source height
  216.  
  217. For Specifying the Output File (Required):
  218. ------------------------------------------
  219. -o [dev:dir/file]     ...24 bit output file (may include path)
  220.  
  221. For Scaling the output file to a percentage of the input file:
  222. --------------------------------------------------------------
  223. -%x [% value]         ...destination image width
  224. -%y [% value]         ...destination image height
  225.  
  226. For Scaling the output file to a specific Pixel Width:
  227. ------------------------------------------------------
  228. -px [pixel value]     ...destination image width
  229. -py [pixel value]     ...destination image height
  230.  
  231. To change an "over-under" X_Spex image to "Interleaved":
  232. --------------------------------------------------------
  233. -3d                   ...takes over-under, makes interleaved
  234.  
  235. To change an "Interleaved" X_Spex image to "over-under":
  236. --------------------------------------------------------
  237. -2d                   ...takes interleaved, makes over-under
  238.  
  239.